home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_HDF.idb / usr / freeware / include / hdf / hfile.h.z / hfile.h
Encoding:
C/C++ Source or Header  |  1999-01-26  |  36.2 KB  |  967 lines
  1. /****************************************************************************
  2.  * NCSA HDF                                                                 *
  3.  * Software Development Group                                               *
  4.  * National Center for Supercomputing Applications                          *
  5.  * University of Illinois at Urbana-Champaign                               *
  6.  * 605 E. Springfield, Champaign IL 61820                                   *
  7.  *                                                                          *
  8.  * For conditions of distribution and use, see the accompanying             *
  9.  * hdf/COPYING file.                                                        *
  10.  *                                                                          *
  11.  ****************************************************************************/
  12.  
  13. /* $Id: hfile.h,v 1.105 1998/02/19 16:27:16 bljones Exp $ */
  14.  
  15. /*+ hfile.h
  16.    *** Header for hfile.c, routines for low level data element I/O
  17.    + */
  18.  
  19. #ifndef HFILE_H
  20. #define HFILE_H
  21.  
  22. #include "tbbt.h"
  23. #include "bitvect.h"
  24. #include "atom.h"
  25. #include "linklist.h"
  26. #include "dynarray.h"
  27.  
  28. /* Magic cookie for HDF data files */
  29. #define MAGICLEN 4  /* length */
  30. #define HDFMAGIC "\016\003\023\001"     /* ^N^C^S^A */
  31.  
  32. /* sizes of elements in a file.  This is necessary because
  33.    the size of variables need not be the same as in the file
  34.    (cannot use sizeof) */
  35. #define DD_SZ 12    /* 2+2+4+4 */
  36. #define NDDS_SZ 2
  37. #define OFFSET_SZ 4
  38.  
  39. /* invalid offset & length to indicate a partially defined element 
  40. * written to the HDF file i.e. can handle the case where the the
  41. * element is defined but not written out */
  42. #define INVALID_OFFSET -1
  43. #define INVALID_LENGTH -1
  44.  
  45.  
  46. /* ----------------------------- Version Tags ----------------------------- */
  47. /* Library version numbers */
  48.  
  49. #define LIBVER_MAJOR    4
  50. #define LIBVER_MINOR    1 
  51. #define LIBVER_RELEASE  2 
  52. #define LIBVER_STRING   "NCSA HDF Version 4.1 Release 2, March 1998"
  53. #define LIBVSTR_LEN    80   /* length of version string  */
  54. #define LIBVER_LEN  92      /* 4+4+4+80 = 92 */
  55. /* end of version tags */
  56.  
  57. /* -------------------------- File I/O Functions -------------------------- */
  58. /* FILELIB -- file library to use for file access: 1 stdio, 2 fcntl
  59.    default to stdio library i.e. UNIX buffered I/O */
  60.  
  61. #ifndef FILELIB
  62. #   define FILELIB UNIXBUFIO    /* UNIX buffered I/O is the default */
  63. #endif /* FILELIB */
  64.  
  65. #if (FILELIB == UNIXBUFIO)
  66. /* using C buffered file I/O routines to access files */
  67. #include <stdio.h>
  68. typedef FILE *hdf_file_t;
  69. #ifdef VMS
  70. /* For VMS, use "mbc=64" to improve performance     */
  71. #   define HI_OPEN(p, a)       (((a) & DFACC_WRITE) ? \
  72.                                 fopen((p), "r+", "mbc=64") : \
  73.                                 fopen((p), "r", "mbc=64"))
  74. #   define HI_CREATE(p)        (fopen((p), "w+", "mbc=64"))
  75. #else  /*  !VMS  */
  76. #if defined SUN && defined (__GNUC__)
  77. #   define HI_OPEN(p, a)       (((a) & DFACC_WRITE) ? \
  78.                                 fopen((p), "r+") : fopen((p), "r"))
  79. #   define HI_CREATE(p)        (fopen((p), "w+"))
  80. #else /* !SUN w/ GNU CC */
  81. #   define HI_OPEN(p, a)       (((a) & DFACC_WRITE) ? \
  82.                                 fopen((p), "rb+") : fopen((p), "rb"))
  83. #   define HI_CREATE(p)        (fopen((p), "wb+"))
  84. #endif /* !SUN w/ GNU CC */
  85. #endif /* VMS */
  86. #   define HI_READ(f, b, n)    (((size_t)(n) == (size_t)fread((b), 1, (size_t)(n), (f))) ? \
  87.                                 SUCCEED : FAIL)
  88. #   define HI_WRITE(f, b, n)   (((size_t)(n) == (size_t)fwrite((b), 1, (size_t)(n), (f))) ? \
  89.                                 SUCCEED : FAIL)
  90. #   define HI_CLOSE(f)   (fclose(f))
  91. #   define HI_FLUSH(f)   (fflush(f)==0 ? SUCCEED : FAIL)
  92. #   define HI_SEEK(f,o)  (fseek((f), (long)(o), SEEK_SET)==0 ? SUCCEED : FAIL)
  93. #   define HI_SEEK_CUR(f,o)  (fseek((f), (long)(o), SEEK_CUR)==0 ? SUCCEED : FAIL)
  94. #   define HI_SEEKEND(f) (fseek((f), (long)0, SEEK_END)==0 ? SUCCEED : FAIL)
  95. #   define HI_TELL(f)    (ftell(f))
  96. #   define OPENERR(f)    ((f) == (FILE *)NULL)
  97. #endif /* FILELIB == UNIXBUFIO */
  98.  
  99. #if (FILELIB == UNIXUNBUFIO)
  100. /* using UNIX unbuffered file I/O routines to access files */
  101. typedef int hdf_file_t;
  102. #   define HI_OPEN(p, a)       (((a) & DFACC_WRITE) ? \
  103.                                     open((p), O_RDWR) : open((p), O_RDONLY))
  104. #   define HI_CREATE(p)         (open((p), O_RDWR | O_CREAT | O_TRUNC, 0666))
  105. #   define HI_CLOSE(f)          (close(f))
  106. #   define HI_FLUSH(f)          (SUCCEED)
  107. #   define HI_READ(f, b, n)     (((n)==read((f), (char *)(b), (n))) ? SUCCEED : FAIL)
  108. #   define HI_WRITE(f, b, n)    (((n)==write((f), (char *)(b), (n))) ? SUCCEED : FAIL)
  109. #   define HI_SEEK(f, o)        (lseek((f), (off_t)(o), SEEK_SET)!=(-1) ? SUCCEED : FAIL)
  110. #   define HI_SEEKEND(f)        (lseek((f), (off_t)0, SEEK_END)!=(-1) ? SUCCEED : FAIL)
  111. #   define HI_TELL(f)           (lseek((f), (off_t)0, SEEK_CUR))
  112. #   define OPENERR(f)           (f < 0)
  113. #endif /* FILELIB == UNIXUNBUFIO */
  114.  
  115. #if (FILELIB == MACIO)
  116. /* using special routines to redirect to Mac Toolkit I/O */
  117. typedef short hdf_file_t;
  118. #   define HI_OPEN(x,y)         mopen(x,y)
  119. #   define HI_CREATE(name)      mopen(name, DFACC_CREATE)
  120. #   define HI_CLOSE(x)          mclose(x)
  121. #   define HI_FLUSH(a)          (SUCCEED)
  122. #   define HI_READ(a,b,c)       mread(a, (char *) b, (int32) c)
  123. #   define HI_WRITE(a,b,c)      mwrite(a, (char *) b, (int32) c)
  124. #   define HI_SEEK(x,y)         mlseek(x, (int32 )y, 0)
  125. #   define HI_SEEKEND(x)        mlseek(x, 0L, 2)
  126. #   define HI_TELL(x)           mlseek(x,0L,1)
  127. #   define DF_OPENERR(f)        ((f) == -1)
  128. #   define OPENERR(f)           (f < 0)
  129. #endif /* FILELIB == MACIO */
  130.  
  131. #ifdef NOT_USED     /* Deprecated routines, not supported any more */
  132. #if (FILELIB == PCIO)
  133. /* using special PC functions to enable reading/writing large chunks */
  134. typedef FILE *hdf_file_t;
  135. #   define HI_OPEN(p, a)       (((a) & DFACC_WRITE) ? \
  136.                                 fopen((p), "rb+") : fopen((p), "rb"))
  137. #   define HI_CREATE(p)        (fopen((p), "wb+"))
  138. /* Alias the HI_READ and HI_WRITE macros to functions which can handle */
  139. /*  32-bits of data to read/write */
  140. #   define HI_READ(f, b, n)    (((int32)(n) == HDfreadbig((b), (n), (f))) ? \
  141.                                 SUCCEED : FAIL)
  142. #   define HI_WRITE(f, b, n)   (((int32)(n) == HDfwritebig((b), (n), (f))) ? \
  143.                                 SUCCEED : FAIL)
  144. #   define HI_CLOSE(f)          (fclose(f))
  145. #   define HI_FLUSH(f)          (fflush(f)==0 ? SUCCEED : FAIL)
  146. #   define HI_SEEK(f,o)  (fseek((f), (long)(o), SEEK_SET)==0 ? SUCCEED : FAIL)
  147. #   define HI_SEEKEND(f) (fseek((f), (long)0, SEEK_END)==0 ? SUCCEED : FAIL)
  148. #   define HI_TELL(f)           (ftell(f))
  149. #   define OPENERR(f)           ((f) == (FILE *)NULL)
  150. #endif /* FILELIB == PCIO */
  151.  
  152. #if (FILELIB == WINIO)
  153. /* using special MS Windows functions to enable reading/writing large chunks */
  154. typedef HFILE hdf_file_t;
  155. #   define HI_OPEN(p, a)       (((a) & DFACC_WRITE) ? \
  156.                                 _lopen((p), READ_WRITE) : _lopen((p), READ))
  157. #   define HI_CREATE(p)        (_lcreat((p), 0))
  158. /* Alias the HI_READ and HI_WRITE macros to functions which can handle */
  159. /*  32-bits of data to read/write */
  160. #   define HI_READ(f, b, n)    (((int32)(n) == HDfreadbig((b), (n), (f))) ? \
  161.                                 SUCCEED : FAIL)
  162. #   define HI_WRITE(f, b, n)   (((int32)(n) == HDfwritebig((b), (n), (f))) ? \
  163.                                 SUCCEED : FAIL)
  164. #   define HI_CLOSE(f)          (_lclose(f))
  165. #   define HI_FLUSH(f)          (0)
  166. #   define HI_SEEK(f, o)        (_llseek((f), (long)(o), SEEK_SET))
  167. #   define HI_SEEKEND(f)        (_llseek((f), (long)0, SEEK_END))
  168. #   define HI_TELL(f)           (_llseek((f),0l,SEEK_CUR))
  169. #   define OPENERR(f)           ((f) == (HFILE)HFILE_ERROR)
  170. #endif /* FILELIB == WINIO */
  171.  
  172. #if (FILELIB == WINNTIO)
  173. /* using special Windows NT functions to enable reading/writing large chunks */
  174. typedef HFILE hdf_file_t;
  175. #   define HI_OPEN(p, a)       (((a) & DFACC_WRITE) ? \
  176.                         _lopen((p), OF_READWRITE) : _lopen((p), OF_READ))
  177. #   define HI_CREATE(p)        (_lcreat((p), 0))
  178. #   define HI_READ(f, b, n)    (((int32)(n) == _hread((f), (b), (n))) ? \
  179.                                 SUCCEED : FAIL)
  180. #   define HI_WRITE(f, b, n)   (((int32)(n) == _hwrite((f), (b), (n))) ? \
  181.                                 SUCCEED : FAIL)
  182. #   define HI_CLOSE(f) (_lclose(f)==0 ? SUCCEED : FAIL)
  183. #   define HI_FLUSH(f) (0)
  184. #   define HI_SEEK(f, o)       (_llseek((f), (long)(o), 0))
  185. #   define HI_SEEKEND(f) (_llseek((f), (long)0, 2))
  186. #   define HI_TELL(f)  (_llseek((f),0l,1))
  187. #   define OPENERR(f)  ((f) == (HFILE)HFILE_ERROR)
  188. #endif /* FILELIB == WINNTIO */
  189. #endif /* NOT_USED */
  190.  
  191. #if (FILELIB == PAGEBUFIO)
  192. #include "fmpio.h"
  193. /* using page buffered file I/O routines to access files */
  194. typedef MPFILE *hdf_file_t;
  195. #   define HI_OPEN(p, a)        (MPopen((p), (a)))
  196. #   define HI_CREATE(p)         (MPopen((p), DFACC_CREATE))
  197. #   define HI_CLOSE(f)          (MPclose(f))
  198. #   define HI_FLUSH(f)          (MPflush(f))
  199. #   define HI_READ(f, b, n)     (MPread((f), (char *)(b), (n)))
  200. #   define HI_WRITE(f, b, n)    (MPwrite((f), (char *)(b), (n)))
  201. #   define HI_SEEK(f, o)        (MPseek((f), (off_t)(o), SEEK_SET))
  202. #   define HI_SEEKEND(f)        (MPseek((f), (off_t)0, SEEK_END))
  203. #   define HI_TELL(f)           (MPseek((f), (off_t)0, SEEK_CUR))
  204. #   define OPENERR(f)           ((f) == (MPFILE *)NULL)
  205. #endif /* FILELIB == PAGEBUFIO */
  206.  
  207. /* ----------------------- Internal Data Structures ----------------------- */
  208. /* The internal structure used to keep track of the files opened: an
  209.    array of filerec_t structures, each has a linked list of ddblock_t.
  210.    Each ddblock_t struct points to an array of dd_t structs. 
  211.  
  212.    File Header(4 bytes)
  213.    ===================
  214.    <--- 32 bits ----->
  215.    ------------------
  216.    |HDF magic number |
  217.    ------------------
  218.  
  219.    HDF magic number - 0x0e031301 (Hexadecimal)
  220.  
  221.    Data Descriptor(DD - 12 bytes)
  222.    ==============================
  223.    <-  16 bits -> <- 16 bits -> <- 32 bits -> <- 32 bits ->
  224.    --------------------------------------------------------
  225.    |    Tag      | reference   |  Offset     |  Length    |
  226.    |             | number      |             |            |
  227.    --------------------------------------------------------
  228.         \____________/
  229.                V
  230.         tag/ref (unique data indentifier in file)
  231.    
  232.    Tag  -- identifies the type of data, 16 bit unsigned integer whose
  233.            value ranges from 1 - 65535. Tags are assigned by NCSA.
  234.            The HDF tag space is divided as follows based on the 2 highest bits:
  235.  
  236.               00: NCSA reserved ordinary tags
  237.               01: NCSA reserved special tags(i.e. regular tags made into 
  238.                                                   linked-block, external, 
  239.                                                   compressed or chunked.)
  240.               10, 11: User tags.
  241.  
  242.            Current tag assingments are:
  243.            00001 - 32767  - reserved for NCSA use
  244.                             00001 - 16383 - NCSA regular tags
  245.                             16384 - 32767 - NCSA special tags
  246.            32768 - 64999  - user definable
  247.            65000 - 65535  - reserved for expansion of format
  248.  
  249.    Refererence number - 16 bit unsigned integer whose assignment is not
  250.           gauranteed to be consecutive. Provides a way to distinguish 
  251.           elements with the same tag in the file.
  252.  
  253.    Offset - Specifies the byte offset of the data element from the 
  254.             beginning of the file - 32 bit unsigned integer
  255.  
  256.    Length - Indicates the byte length of the data element
  257.             32 bit unsigned integer
  258.  
  259.    Data Descriptor Header(DDH - 6 bytes)
  260.    ====================================
  261.    <-  16 bits -> <- 32 bits ->
  262.    -----------------------------
  263.    | Block Size  | Next Block  |
  264.    -----------------------------
  265.  
  266.    Block Size - Indicates the number of DD's in the DD Block,
  267.                 16 bit unsigned integer value
  268.    Next Block - Gives the offset of the next DD Block. The last DD Block has
  269.                 a ZERO(0) in the "Next Block" field in the DDH.
  270.                 32 bit unsigned integer value
  271.  
  272.    Data Descriptor Block(DDB - variable size)
  273.    ==========================================
  274.    <- DD Header -> <--------------- DD's --------------------->
  275.    --------------------------------------------------------...-
  276.    |Block | Next  | DD | DD | DD | DD | DD | DD | DD | DD |...|
  277.    |Size  | Block |    |    |    |    |    |    |    |    |   |
  278.    --------------------------------------------------------...-
  279.    <-------------------------- DD Block ---------------------->
  280.  
  281.    Note: default number of DD's in a DD Block is 16
  282.  
  283.    HDF file layout
  284.    =============================
  285.    (one example)
  286.    ---------------------------------------------------------------------
  287.    | FH | DD Block | Data | DD Block | Data | DD Block | Data | .....
  288.    ---------------------------------------------------------------------
  289.  
  290. */
  291.  
  292. /* record of each data decsriptor */
  293. typedef struct dd_t
  294.   {
  295.       uint16      tag;          /* Tag number of element i.e. type of data */
  296.       uint16      ref;          /* Reference number of element */
  297.       int32       length;       /* length of data element */
  298.       int32       offset;       /* byte offset of data element from */
  299.       struct ddblock_t *blk;    /* Pointer to the block this dd is in */
  300.   }                             /* beginning of file */
  301. dd_t;
  302.  
  303. /* version tags */
  304. typedef struct version_t
  305.   {
  306.       uint32      majorv;       /* major version number */
  307.       uint32      minorv;       /* minor version number */
  308.       uint32      release;      /* release number */
  309.       char        string[LIBVSTR_LEN + 1];  /* optional text description, len 80+1 */
  310.       int16       modified;     /* indicates file was modified */
  311.   }
  312. version_t;
  313.  
  314. /* record of a block of data descriptors, mirrors structure of a HDF file.  */
  315. typedef struct ddblock_t
  316.   {
  317.       uintn       dirty;        /* boolean: should this DD block be flushed? */
  318.       int32       myoffset;     /* offset of this DD block in the file */
  319.       int16       ndds;         /* number of dd's in this block */
  320.       int32       nextoffset;   /* offset to the next ddblock in the file */
  321.       struct filerec_t *frec;   /* Pointer to the filerec this block is in */
  322.       struct ddblock_t *next;   /* pointer to the next ddblock in memory */
  323.       struct ddblock_t *prev;   /* Pointer to previous ddblock. */
  324.       struct dd_t *ddlist;      /* pointer to array of dd's */
  325.   }
  326. ddblock_t;
  327.  
  328. /* Tag tree node structure */
  329. typedef struct tag_info_str
  330.   {
  331.       uint16 tag;       /* tag value for this node */
  332.       /* Needs to be first in this structure */
  333.       bv_ptr b;         /* bit-vector to keep track of which refs are used */
  334.       dynarr_p d;       /* dynarray of the refs for this tag */
  335.   }tag_info;
  336.  
  337. /* For determining what the last file operation was */
  338. typedef enum
  339.   {
  340.       OP_UNKNOWN = 0,   /* Don't know what the last operation was (after fopen frex) */
  341.       OP_SEEK,          /* Last operation was a seek */
  342.       OP_WRITE,         /* Last operation was a write */
  343.       OP_READ           /* Last operation was a read */
  344.   }
  345. fileop_t;
  346.  
  347. /* File record structure */
  348. typedef struct filerec_t
  349.   {
  350.       char       *path;         /* name of file */
  351.       hdf_file_t  file;         /* either file descriptor or pointer */
  352.       uint16      maxref;       /* highest ref in this file */
  353.       intn        access;       /* access mode */
  354.       intn        refcount;     /* reference count / times opened */
  355.       intn        attach;       /* number of access elts attached */
  356.       intn        version_set;  /* version tag stuff */
  357.       version_t   version;      /* file version info */
  358.  
  359.       /* Seek caching info */
  360.       int32      f_cur_off;    /* Current location in the file */
  361.       fileop_t    last_op;      /* the last file operation performed */
  362.  
  363.       /* DD block caching info */
  364.       intn        cache;        /* boolean: whether caching is on */
  365.       intn        dirty;        /* boolean: if dd list needs to be flushed */
  366.       int32      f_end_off;    /* offset of the end of the file */
  367.  
  368.       /* DD list pointers */
  369.       struct ddblock_t *ddhead; /* head of ddblock list */
  370.       struct ddblock_t *ddlast; /* end of ddblock list */
  371.  
  372.       /* NULL DD pointers (for fast lookup of DFTAG_NULL) */
  373.       struct ddblock_t *ddnull; /* location of last ddblock with a DFTAG_NULL */
  374.       int32       ddnull_idx;   /* offset of the last location with DFTAG_NULL */
  375.  
  376.       /* tag tree for file */
  377.       TBBT_TREE *tag_tree;      /* TBBT of the tags in the file */
  378.  
  379.       /* annotation stuff for file */
  380.       intn       an_num[4];   /* Holds number of annotations found of each type */
  381.       TBBT_TREE *an_tree[4];  /* tbbt trees for each type of annotation in file 
  382.                                * i.e. file/data labels and descriptions.
  383.                                * This is done for faster searching of annotations
  384.                                * of a particular type. */
  385.   }
  386. filerec_t;
  387.  
  388. /* bits for filerec_t 'dirty' flag */
  389. #define DDLIST_DIRTY   0x01     /* mark whether to flush dirty DD blocks */
  390. #define FILE_END_DIRTY 0x02     /* indicate that the file needs to be extended */
  391.  
  392. /* Each access element is associated with a tag/ref to keep track of
  393.    the dd it is pointing at.  To facilitate searching for next dd's,
  394.    instead of pointing directly to the dd, we point to the ddblock and
  395.    index into the ddlist of that ddblock. */
  396. typedef struct accrec_t
  397.   {
  398.       /* Flags for this access record */
  399.       intn        appendable;   /* whether appends to the data are allowed */
  400.       intn        special;      /* special element ? */
  401.       intn        new_elem;     /* is a new element (i.e. no length set yet) */
  402.       
  403.       uint32      access;       /* access codes */
  404.       uintn       access_type;  /* I/O access type: serial/parallel/... */
  405.       int32       file_id;      /* id of attached file */
  406.       atom_t      ddid;         /* DD id for the DD attached to */
  407.       int32       posn;         /* seek position with respect to start of element */
  408.       void *       special_info; /* special element info? */
  409.       struct funclist_t *special_func;  /* ptr to special function? */
  410.       struct accrec_t *next;    /* for free-list linking */
  411.   }
  412. accrec_t;
  413.  
  414. #ifdef HFILE_MASTER
  415. /* Pointer to the access record node free list */
  416. static accrec_t *accrec_free_list=NULL;
  417. #endif /* HFILE_MASTER */
  418.  
  419. /* this type is returned to applications programs or other special
  420.    interfaces when they need to know information about a given
  421.    special element.  This is all information that would not be returned
  422.    via Hinquire().  This should probably be a union of structures. */
  423. typedef struct sp_info_block_t
  424.   {
  425.       int16       key;          /* type of special element this is */
  426.  
  427.       /* external elements */
  428.       int32       offset;       /* offset in the file */
  429.       char       *path;         /* file name - should not be freed by user */
  430.  
  431.       /* linked blocks */
  432.       int32       first_len;    /* length of first block */
  433.       int32       block_len;    /* length of standard block */
  434.       int32       nblocks;      /* number of blocks per chunk */
  435.  
  436.       /* compressed elements */
  437.       int32       comp_type;    /* compression type */
  438.       int32       model_type;   /* model type */
  439.       int32       comp_size;    /* size of compressed information */
  440.  
  441.       /* variable-length linked blocks */
  442.       int32       min_block;    /* the minimum block size */
  443.  
  444.     /* Chunked elements */
  445.       int32       chunk_size;   /* logical size of chunks */
  446.       int32       ndims;        /* number of dimensions */
  447.       int32       *cdims;       /* array of chunk lengths for each dimension */
  448.   }
  449. sp_info_block_t;
  450.  
  451. /* a function table record for accessing special data elements.
  452.    special data elements of a key could be accessed through the list
  453.    of functions in array pointed to by tab. */
  454. typedef struct funclist_t
  455.   {
  456.       int32       (*stread) (accrec_t * rec);
  457.       int32       (*stwrite) (accrec_t * rec);
  458.       int32       (*seek) (accrec_t * access_rec, int32 offset, intn origin);
  459.       int32       (*inquire) (accrec_t * access_rec, int32 *pfile_id,
  460.                                  uint16 *ptag, uint16 *pref, int32 *plength,
  461.                                int32 *poffset, int32 *pposn, int16 *paccess,
  462.                                      int16 *pspecial);
  463.       int32       (*read) (accrec_t * access_rec, int32 length, void * data);
  464.       int32       (*write) (accrec_t * access_rec, int32 length, const void * data);
  465.       intn        (*endaccess) (accrec_t * access_rec);
  466.       int32       (*info) (accrec_t * access_rec, sp_info_block_t * info);
  467.       int32       (*reset) (accrec_t * access_rec, sp_info_block_t * info);
  468.   }
  469. funclist_t;
  470.  
  471. typedef struct functab_t
  472.   {
  473.       int16       key;          /* the key for this type of special elt */
  474.       funclist_t *tab;          /* table of accessing functions */
  475.   }
  476. functab_t;
  477.  
  478. /* ---------------------- ID Types and Manipulation ----------------------- */
  479. /* each id, what ever the type, will be represented with a 32-bit word,
  480.    the most-significant 16 bits is a number unique for type.  The less-
  481.    significant 16 bits is an id unique to each type; in this, we use the
  482.    internal slot number. */
  483.  
  484. #define FIDTYPE   1
  485. #define AIDTYPE   2
  486. #define GROUPTYPE 3
  487. #define SDSTYPE   4
  488. #define DIMTYPE   5
  489. #define CDFTYPE   6
  490. #define VGIDTYPE  8     /* also defined in vg.h for Vgroups */
  491. #define VSIDTYPE  9     /* also defined in vg.h for Vsets */
  492. #define BITTYPE   10    /* For bit-accesses */
  493. #define GRIDTYPE  11    /* for GR access */
  494. #define RIIDTYPE  12    /* for RI access */
  495.  
  496. #define BADFREC(r)  ((r)==NULL || (r)->refcount==0)
  497.  
  498. /* --------------------------- Special Elements --------------------------- */
  499. /* The HDF tag space is divided as follows based on the 2 highest bits:
  500.    00: NCSA reserved ordinary tags
  501.    01: NCSA reserved special tags(e.g. linked-block, external, compressed,..)
  502.    10, 11: User tags.
  503.  
  504.    It is relatively cheap to operate with special tags within the NCSA
  505.    reserved tags range. For users to specify special tags and their
  506.    corresponding ordinary tag, the pair has to be added to the
  507.    special_table in hfile.c and SPECIAL_TABLE must be defined. */
  508.  
  509. #ifdef SPECIAL_TABLE
  510. #define BASETAG(t)      (HDbase_tag(t))
  511. #define SPECIALTAG(t)   (HDis_special_tag(t))
  512. #define MKSPECIALTAG(t) (HDmake_special_tag(t))
  513. #else
  514. /* This macro converts a (potentially) special tag into a normal tag */
  515. #define BASETAG(t)      (uint16)((~(t) & 0x8000) ? ((t) & ~0x4000) : (t))
  516. /* This macro checks if a tag is special */
  517. #define SPECIALTAG(t)   (uint16)((~(t) & 0x8000) && ((t) & 0x4000))
  518. /* This macro (potentially) converts a regular tag into a special tag */
  519. #define MKSPECIALTAG(t) (uint16)((~(t) & 0x8000) ? ((t) | 0x4000) : DFTAG_NULL)
  520. #endif /*SPECIAL_TABLE */
  521.  
  522. /* -------------------------- H-Layer Prototypes -------------------------- */
  523. /*
  524.    ** Functions to get information of special elt from other access records.
  525.    **   defined in hfile.c
  526.    ** These should really be HD... routines, but they are only used within
  527.    **   the H-layer...
  528.  */
  529.  
  530. #if defined c_plusplus || defined __cplusplus
  531. extern      "C"
  532. {
  533. #endif                          /* c_plusplus || __cplusplus */
  534.  
  535.     extern accrec_t *HIget_access_rec
  536.                 (void);
  537.  
  538.     extern void HIrelease_accrec_node(accrec_t *acc);
  539.  
  540.     extern void * HIgetspinfo
  541.                 (accrec_t * access_rec);
  542.  
  543.     extern intn HPcompare_filerec_path
  544.                 (const void * obj, const void * key);
  545.  
  546.     extern intn HPcompare_accrec_tagref
  547.                 (const void * rec1, const void * rec2);
  548.  
  549.     extern int32 HPgetdiskblock
  550.                 (filerec_t * file_rec, int32 block_size, intn moveto);
  551.  
  552.     extern intn HPfreediskblock
  553.                 (filerec_t * file_rec, int32 block_offset, int32 block_size);
  554.  
  555.     extern int32 HDget_special_info
  556.                 (int32 access_id, sp_info_block_t * info_block);
  557.  
  558.     extern intn HP_read
  559.                 (filerec_t *file_rec,void * buf,int32 bytes);
  560.  
  561.     extern intn HPseek
  562.                 (filerec_t *file_rec,int32 offset);
  563.  
  564.     extern intn HP_write
  565.                 (filerec_t *file_rec,const void * buf,int32 bytes);
  566.  
  567.     extern intn tagcompare
  568.                 (void * k1, void * k2, intn cmparg);
  569.  
  570.     extern VOID tagdestroynode
  571.                 (void * n);
  572.  
  573. /*
  574.    ** from hblocks.c
  575.  */
  576.     extern int32 HLPstread
  577.                 (accrec_t * access_rec);
  578.  
  579.     extern int32 HLPstwrite
  580.                 (accrec_t * access_rec);
  581.  
  582.     extern int32 HLPseek
  583.                 (accrec_t * access_rec, int32 offset, int origin);
  584.  
  585.     extern int32 HLPread
  586.                 (accrec_t * access_rec, int32 length, void * data);
  587.  
  588.     extern int32 HLPwrite
  589.                 (accrec_t * access_rec, int32 length, const void * data);
  590.  
  591.     extern int32 HLPinquire
  592.                 (accrec_t * access_rec, int32 *pfile_id, uint16 *ptag, uint16 *pref,
  593.                int32 *plength, int32 *poffset, int32 *pposn, int16 *paccess,
  594.                  int16 *pspecial);
  595.  
  596.     extern intn HLPendaccess
  597.                 (accrec_t * access_rec);
  598.  
  599.     extern int32 HLPcloseAID
  600.                 (accrec_t * access_rec);
  601.  
  602.     extern int32 HLPinfo
  603.                 (accrec_t * access_rec, sp_info_block_t * info_block);
  604.  
  605. /*
  606.    ** from hextelt.c
  607.  */
  608.     extern int32 HXPstread
  609.                 (accrec_t * rec);
  610.  
  611.     extern int32 HXPstwrite
  612.                 (accrec_t * rec);
  613.  
  614.     extern int32 HXPseek
  615.                 (accrec_t * access_rec, int32 offset, int origin);
  616.  
  617.     extern int32 HXPread
  618.                 (accrec_t * access_rec, int32 length, void * data);
  619.  
  620.     extern int32 HXPwrite
  621.                 (accrec_t * access_rec, int32 length, const void * data);
  622.  
  623.     extern int32 HXPinquire
  624.                 (accrec_t * access_rec, int32 *pfile_id, uint16 *ptag, uint16 *pref,
  625.                int32 *plength, int32 *poffset, int32 *pposn, int16 *paccess,
  626.                  int16 *pspecial);
  627.  
  628.     extern intn HXPendaccess
  629.                 (accrec_t * access_rec);
  630.  
  631.     extern int32 HXPcloseAID
  632.                 (accrec_t * access_rec);
  633.  
  634.     extern int32 HXPinfo
  635.                 (accrec_t * access_rec, sp_info_block_t * info_block);
  636.  
  637.     extern int32 HXPreset
  638.                 (accrec_t * access_rec, sp_info_block_t * info_block);
  639.  
  640.     extern intn HXPsetaccesstype
  641.                 (accrec_t * access_rec);
  642.  
  643.     extern intn HXPshutdown
  644.                 (void);
  645.  
  646. /*
  647.    ** from hcomp.c
  648.  */
  649.  
  650.     extern int32 HCPstread
  651.                 (accrec_t * rec);
  652.  
  653.     extern int32 HCPstwrite
  654.                 (accrec_t * rec);
  655.  
  656.     extern int32 HCPseek
  657.                 (accrec_t * access_rec, int32 offset, int origin);
  658.  
  659.     extern int32 HCPinquire
  660.                 (accrec_t * access_rec, int32 *pfile_id, uint16 *ptag, uint16 *pref,
  661.                int32 *plength, int32 *poffset, int32 *pposn, int16 *paccess,
  662.                  int16 *pspecial);
  663.  
  664.     extern int32 HCPread
  665.                 (accrec_t * access_rec, int32 length, void * data);
  666.  
  667.     extern int32 HCPwrite
  668.                 (accrec_t * access_rec, int32 length, const void * data);
  669.  
  670.     extern intn HCPendaccess
  671.                 (accrec_t * access_rec);
  672.  
  673.     extern int32 HCPcloseAID
  674.                 (accrec_t * access_rec);
  675.  
  676.     extern int32 HCPinfo
  677.                 (accrec_t * access_rec, sp_info_block_t * info_block);
  678.  
  679. /*
  680.    ** from hvblocks.c
  681.  */
  682.  
  683.     extern int32 HVPstread
  684.                 (accrec_t * rec);
  685.  
  686.     extern int32 HVPstwrite
  687.                 (accrec_t * rec);
  688.  
  689.     extern int32 HVPseek
  690.                 (accrec_t * access_rec, int32 offset, int origin);
  691.  
  692.     extern int32 HVPinquire
  693.                 (accrec_t * access_rec, int32 *pfile_id, uint16 *ptag, uint16 *pref,
  694.                int32 *plength, int32 *poffset, int32 *pposn, int16 *paccess,
  695.                  int16 *pspecial);
  696.  
  697.     extern int32 HVPread
  698.                 (accrec_t * access_rec, int32 length, void * data);
  699.  
  700.     extern int32 HVPwrite
  701.                 (accrec_t * access_rec, int32 length, const void * data);
  702.  
  703.     extern intn HVPendaccess
  704.                 (accrec_t * access_rec);
  705.  
  706.     extern int32 HVPinfo
  707.                 (accrec_t * access_rec, sp_info_block_t * info_block);
  708.  
  709. /*
  710.    ** from hchunks.c - should be the same as found in 'hchunks.h'
  711.  */
  712. #include "hchunks.h"
  713.  
  714. #if defined (MAC) || defined (macintosh) || defined (SYMANTEC_C)
  715.     extern hdf_file_t mopen
  716.                 (char *filename, intn access);
  717.  
  718.     extern int32 mclose
  719.                 (hdf_file_t rn);
  720.  
  721.     extern int32 mlseek
  722.                 (hdf_file_t rn, int32 n, intn m);
  723.  
  724.     extern int32 mread
  725.                 (hdf_file_t rn, char *buf, int32 n);
  726.  
  727.     extern int32 mwrite
  728.                 (hdf_file_t rn, char *buf, int32 n);
  729.     extern intn mstat
  730.                 (char *path);
  731.  
  732. #endif  /* macintosh */
  733.  
  734. /*
  735.    ** from hfiledd.c
  736.  */
  737. /******************************************************************************
  738.  NAME
  739.      HTPstart - Initialize the DD list in memory
  740.  
  741.  DESCRIPTION
  742.     Reads the DD blocks from disk and creates the in-memory structures for
  743.     handling them.  This routine should only be called once for a given
  744.     file and HTPend should be called when finished with the DD list (i.e.
  745.     when the file is being closed).
  746.  
  747.  RETURNS
  748.     Returns SUCCEED if successful and FAIL otherwise
  749.  
  750. *******************************************************************************/
  751. intn HTPstart(filerec_t *file_rec       /* IN:  File record to store info in */
  752. );
  753.  
  754. /******************************************************************************
  755.  NAME
  756.      HTPinit - Create a new DD list in memory
  757.  
  758.  DESCRIPTION
  759.     Creates a new DD list in memory for a newly created file.  This routine
  760.     should only be called once for a given file and HTPend should be called
  761.     when finished with the DD list (i.e.  when the file is being closed).
  762.  
  763.  RETURNS
  764.     Returns SUCCEED if successful and FAIL otherwise
  765.  
  766. *******************************************************************************/
  767. intn HTPinit(filerec_t *file_rec,       /* IN: File record to store info in */
  768.     int16 ndds                          /* IN: # of DDs to store in each block */
  769. );
  770.  
  771. /******************************************************************************
  772.  NAME
  773.      HTPsync - Flush the DD list in memory
  774.  
  775.  DESCRIPTION
  776.     Syncronizes the in-memory copy of the DD list with the copy on disk by
  777.     writing out the DD blocks which have changed to disk.
  778.     
  779.  RETURNS
  780.     Returns SUCCEED if successful and FAIL otherwise
  781.  
  782. *******************************************************************************/
  783. intn HTPsync(filerec_t *file_rec       /* IN:  File record to store info in */
  784. );
  785.  
  786. /******************************************************************************
  787.  NAME
  788.      HTPend - Terminate the DD list in memory
  789.  
  790.  DESCRIPTION
  791.     Terminates access to the DD list in memory, writing the DD blocks out to
  792.     the disk (if they've changed).  After this routine is called, no further
  793.     access to tag/refs (or essentially any other HDF objects) can be performed
  794.     on the file.
  795.  
  796.  RETURNS
  797.     Returns SUCCEED if successful and FAIL otherwise
  798.  
  799. *******************************************************************************/
  800. intn HTPend(filerec_t *file_rec       /* IN:  File record to store info in */
  801. ); 
  802.  
  803. /******************************************************************************
  804.  NAME
  805.      HTPcreate - Create (and attach to) a tag/ref pair
  806.  
  807.  DESCRIPTION
  808.     Creates a new tag/ref pair in memory and inserts the tag/ref pair into the
  809.     DD list to be written out to disk.  This routine returns a DD id which can
  810.     be used in the other tag/ref routines to modify the DD.
  811.  
  812.  RETURNS
  813.     Returns DD id if successful and FAIL otherwise
  814.  
  815. *******************************************************************************/
  816. atom_t HTPcreate(filerec_t *file_rec,   /* IN: File record to store info in */
  817.     uint16 tag,                         /* IN: Tag to create */
  818.     uint16 ref                          /* IN: ref to create */
  819. );
  820.  
  821. /******************************************************************************
  822.  NAME
  823.      HTPselect - Attach to an existing tag/ref pair
  824.  
  825.  DESCRIPTION
  826.     Attaches to an existing tag/ref pair.  This routine returns a DD id which
  827.     can be used in the other tag/ref routines to modify the DD.
  828.  
  829.  RETURNS
  830.     Returns DD id if successful and FAIL otherwise
  831.  
  832. *******************************************************************************/
  833. atom_t HTPselect(filerec_t *file_rec,   /* IN: File record to store info in */
  834.     uint16 tag,                         /* IN: Tag to select */
  835.     uint16 ref                          /* IN: ref to select */
  836. );
  837.  
  838. /******************************************************************************
  839.  NAME
  840.      HTPendaccess - End access to an existing tag/ref pair
  841.  
  842.  DESCRIPTION
  843.     Ends access to an existing tag/ref pair.  Any further access to the tag/ref
  844.     pair may result in incorrect information being recorded about the DD in
  845.     memory or on disk.
  846.  
  847.  RETURNS
  848.     Returns SUCCEED if successful and FAIL otherwise
  849.  
  850. *******************************************************************************/
  851. intn HTPendaccess(atom_t ddid           /* IN: DD id to end access to */
  852. );
  853.  
  854. /******************************************************************************
  855.  NAME
  856.      HTPdelete - Delete an existing tag/ref pair
  857.  
  858.  DESCRIPTION
  859.     Deletes a tag/ref from the file.  Also ends access to the tag/ref pair.
  860.     Any further access to the tag/ref pair may result in incorrect information
  861.     being recorded about the DD in memory or on disk.
  862.  
  863.  RETURNS
  864.     Returns SUCCEED if successful and FAIL otherwise
  865.  
  866. *******************************************************************************/
  867. intn HTPdelete(atom_t ddid              /* IN: DD id to delete */
  868. );
  869.  
  870. /******************************************************************************
  871.  NAME
  872.      HTPupdate - Change the offset or length of an existing tag/ref pair
  873.  
  874.  DESCRIPTION
  875.     Updates a tag/ref in the file, allowing the length and/or offset to be
  876.     modified. Note: "INVALID_OFFSET" & "INVALID_LENGTH" are used to indicate
  877.     that the length or offset (respectively) is unchanged.
  878.  
  879.  RETURNS
  880.     Returns SUCCEED if successful and FAIL otherwise
  881.  
  882. *******************************************************************************/
  883. intn HTPupdate(atom_t ddid,             /* IN: DD id to update */
  884.     int32 new_off,                      /* IN: new offset for DD */
  885.     int32 new_len                       /* IN: new length for DD */
  886. );
  887.  
  888. /******************************************************************************
  889.  NAME
  890.      HTPinquire - Get the DD information for a DD (i.e. tag/ref/offset/length)
  891.  
  892.  DESCRIPTION
  893.     Get the DD information for a DD id from the DD block.  Passing NULL for
  894.     any parameter does not try to update that parameter.
  895.  
  896.  RETURNS
  897.     Returns SUCCEED if successful and FAIL otherwise
  898.  
  899. *******************************************************************************/
  900. intn HTPinquire(atom_t ddid,            /* IN: DD id to inquire about */
  901.     uint16 *tag,                        /* IN: tag of DD */
  902.     uint16 *ref,                        /* IN: ref of DD */
  903.     int32 *off,                         /* IN: offset of DD */
  904.     int32 *len                          /* IN: length of DD */
  905. );
  906.  
  907. /******************************************************************************
  908.  NAME
  909.      HTPis_special - Check if a DD id is associated with a special tag
  910.  
  911.  DESCRIPTION
  912.     Checks if the tag for the DD id is a special tag.
  913.  
  914.  RETURNS
  915.     Returns TRUE(1)/FALSE(0) if successful and FAIL otherwise
  916.  
  917. *******************************************************************************/
  918. intn HTPis_special(atom_t ddid             /* IN: DD id to inquire about */
  919. );
  920.  
  921. /******************************************************************************
  922.  NAME
  923.     HTPdump_dds -- Dump out the dd information for a file
  924.  
  925.  DESCRIPTION
  926.     Prints out all the information (that you could _ever_ want to know) about
  927.     the dd blocks and dd list for a file.
  928.  
  929.  RETURNS
  930.     returns SUCCEED (0) if successful and FAIL (-1) if failed.
  931.  
  932. *******************************************************************************/
  933. intn HTPdump_dds(int32 file_id,     /* IN: file ID of HDF file to dump info for */
  934.     FILE *fout                      /* IN: file stream to output to */
  935. );
  936.  
  937. #if defined c_plusplus || defined __cplusplus
  938. }
  939. #endif                          /* c_plusplus || __cplusplus */
  940.  
  941. /* #define DISKBLOCK_DEBUG */
  942. #ifdef DISKBLOCK_DEBUG
  943.  
  944. #ifndef HFILE_MASTER
  945. extern
  946. #endif /* HFILE_MASTER */
  947. const uint8 diskblock_header[4]
  948. #ifdef HFILE_MASTER
  949. ={0xde, 0xad, 0xbe, 0xef}
  950. #endif /* HFILE_MASTER */
  951. ;
  952.  
  953. #ifndef HFILE_MASTER
  954. extern
  955. #endif /* HFILE_MASTER */
  956. const uint8 diskblock_tail[4]
  957. #ifdef HFILE_MASTER
  958. ={0xfe, 0xeb, 0xda, 0xed}
  959. #endif /* HFILE_MASTER */
  960. ;
  961. #define DISKBLOCK_HSIZE sizeof(diskblock_header)
  962. #define DISKBLOCK_TSIZE sizeof(diskblock_tail)
  963.  
  964. #endif /* DISKBLOCK_DEBUG */
  965.  
  966. #endif                          /* HFILE_H */
  967.